lab components / Actions and controls

Period picker

Allow users to select a range of dates quickly and intuitively.

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { PeriodPicker } from "@siteimprove/fancylab";

#Examples

Default: Button shows selected range with presets available. Always has a default presets with the most commonly used date range.

Period picker consists of two main elements:

Button (with clock icon) using two lines:
- Line 1: Active preset or custom date range.
- Line 2: Start and end dates of selected range
Popover (triggered by button click) with:
- Preset tabs (e.g., "Last 7 Days," "Last Month")
- Interactive calendar view for custom range selection

CodeHTML output

const [period, setPeriod] = React.useState<PeriodPickerValue | null>({
	start: new Date(2023, 4, 1),
	end: new Date(2023, 4, 31),
	type: PeriodType.Custom,
});

return <PeriodPicker aria-label="Select period" value={period} onChange={setPeriod} />;

#Usage with hidden presets

Used when preset data is unavailable, focusing on custom selection.

CodeHTML output

const [period, setPeriod] = React.useState<PeriodPickerValue | null>({
	start: new Date(2023, 4, 1),
	end: new Date(2023, 4, 31),
	type: PeriodType.Custom,
});

return (
	<PeriodPicker
		aria-label="Select period"
		value={period}
		onChange={setPeriod}
		hiddenPresets={[
			PeriodType.LastSevenDays,
			PeriodType.LastFourteenDays,
			PeriodType.LastThirtyDays,
			PeriodType.Last365Days,
		]}
	/>
);

#Usage with condensed variant

Button (with clock icon) displaying selected range in one line.

CodeHTML output

const [period, setPeriod] = React.useState<PeriodPickerValue | null>({
	start: new Date(2023, 4, 1),
	end: new Date(2023, 4, 31),
	type: PeriodType.Custom,
});

return <PeriodPicker aria-label="Select period" value={period} onChange={setPeriod} condensed />;

#Usage with time zone conversion

When the dates are provided in UTC format (e.g. when dates from the server are not localized) make sure to convert it from UTC to local when passed to the value prop and from local to UTC when updating the period state from within the onChange callback.

CodeHTML output

const [period, setPeriod] = React.useState<PeriodPickerValue | null>({
	start: new Date(2023, 4, 1),
	end: new Date(2023, 4, 31),
	type: PeriodType.Custom,
});

function localToUtc(date: Date): Date {
	return new Date(
		Date.UTC(
			date.getFullYear(),
			date.getMonth(),
			date.getDate(),
			date.getHours(),
			date.getMinutes(),
			date.getSeconds()
		)
	);
}

function utcToLocal(date: Date): Date {
	return new Date(
		date.getUTCFullYear(),
		date.getUTCMonth(),
		date.getUTCDate(),
		date.getUTCHours(),
		date.getUTCMinutes(),
		date.getUTCSeconds()
	);
}

return (
	<PeriodPicker
		aria-label="Select period"
		value={
			period
				? {
						start: utcToLocal(period.start),
						end: utcToLocal(period.end),
						type: period.type,
				  }
				: null
		}
		onChange={(period) => {
			setPeriod(
				period
					? {
							start: localToUtc(period.start),
							end: localToUtc(period.end),
							type: period.type,
					  }
					: null
			);
		}}
	/>
);

#Usage with UTC offset

When a UTC offset is provided, all preset calculations (such as "Last 5 minutes", "Yesterday", etc.) are based on the current time adjusted by that offset. This means "now" reflects the time at the specified UTC offset, not the system or browser time.

Start: 2025-08-27T14:12:26.751Z

End: 2025-08-27T14:17:26.751Z

CodeHTML output

const utcOffset = -10 * 60; // Example UTC offset in minutes (-10 hours)

const now = new Date();
now.setMinutes(now.getMinutes() + utcOffset); // Adjust current time by UTC offset
const start = new Date(now.getTime() - 5 * 60 * 1000); // 5 minutes ago
const end = new Date(now);

const [period, setPeriod] = React.useState<PeriodPickerValue | null>({
	start,
	end,
	type: PeriodType.Now,
});

return (
	<Content flexDirection="row" padding="none" gap="large">
		<PeriodPicker
			aria-label="Select period"
			value={period}
			onChange={setPeriod}
			options={{ utcOffset }}
		/>
		{period && (
			<div>
				<div>
					<InlineText>{`Start: ${period.start.toISOString()}`}</InlineText>
				</div>
				<div>
					<InlineText>{`End: ${period.end.toISOString()}`}</InlineText>
				</div>
			</div>
		)}
	</Content>
);

#Usage with includeToday option

When includeToday: false is set, the "This Month", "This Quarter", and "This Year" presets will end at yesterday instead of today. By default, includeToday is true.

Start: 2023-05-01T00:00:00.000Z

End: 2023-05-31T00:00:00.000Z

CodeHTML output

const [period, setPeriod] = React.useState<PeriodPickerValue | null>({
	start: new Date(2023, 4, 1),
	end: new Date(2023, 4, 31),
	type: PeriodType.Custom,
});

return (
	<Content flexDirection="row" padding="none" gap="large">
		<PeriodPicker
			aria-label="Select period with includeToday option"
			value={period}
			onChange={setPeriod}
			options={{ includeToday: false }}
		/>
		{period && (
			<div>
				<div>
					<InlineText>{`Start: ${period.start.toISOString()}`}</InlineText>
				</div>
				<div>
					<InlineText>{`End: ${period.end.toISOString()}`}</InlineText>
				</div>
			</div>
		)}
	</Content>
);

#Usage with week start

When a week start is provided, the calendar view will start the week on the specified day. This is useful when the user's locale or system week start day is different from the default (Sunday).

Start: 2023-05-01T00:00:00.000Z

End: 2023-05-31T00:00:00.000Z

CodeHTML output

const [period, setPeriod] = React.useState<PeriodPickerValue | null>({
	start: new Date(2023, 4, 1),
	end: new Date(2023, 4, 31),
	type: PeriodType.Custom,
});

return (
	<Content flexDirection="row" padding="none" gap="large">
		<PeriodPicker
			aria-label="Select period with week starting Monday"
			value={period}
			onChange={setPeriod}
			options={{ weekStart: 1 }} // 0 = Sunday, 1 = Monday, 2 = Tuesday, etc.
		/>
		{period && (
			<div>
				<div>
					<InlineText>{`Start: ${period.start.toISOString()}`}</InlineText>
				</div>
				<div>
					<InlineText>{`End: ${period.end.toISOString()}`}</InlineText>
				</div>
			</div>
		)}
	</Content>
);

#Properties

CodePropsHTML output

Property	Description	Defined	Value
valueRequired	`\| object`The value of the component	YesNo
onChangeRequired	`function`Callback that is called when the value changes	YesNo
optionsOptional	`object`Options for period calculations	YesNo
minDateOptional	`date`	YesNo
maxDateOptional	`date`	YesNo
hiddenPresetsOptional	`literal-union[]`	YesNo
condensedOptional	`boolean`	YesNo	truefalse
disabledOptional	`boolean`Whether the component is disabled	YesNo	truefalse
aria-labelOptional	`string`Label of the form control	YesNo
aria-describedbyOptional	`string`ID of an an element that describes what the form control is for	YesNo
aria-labelledbyOptional	`string`ID of an an element that labels this form control	YesNo
periodButtonVariantOptional	`"borderless" \| "ctaDefault" \| "ctaPrimary" \| "ctaSecondary" \| "default" \| "destructive" \| "primary" \| "secondary"`How should the button look	YesNo
periodButtonSizeOptional	`"large" \| "medium" \| "small"`Controls the size of the button - defaults to medium	YesNo
periodButtonStyleOptional	`object`Add inline style for the button only if necessary	YesNo
strategyOptional	`"absolute" \| "fixed"`Position popover using fixed or absolute	YesNo
data-observe-keyOptional	`string`Unique string, used by external script e.g. for event tracking	YesNo
classNameOptional	`string`Custom className that's applied to the outermost element (only intended for special cases)	YesNo
styleOptional	`object`Style object to apply custom inline styles (only intended for special cases)	YesNo
tabIndexOptional	`number`Tab index of the outermost HTML element of the component	YesNo
onKeyDownOptional	`function`Callback for onKeyDown event	YesNo
onMouseDownOptional	`function`Callback for onMouseDown event	YesNo
onMouseEnterOptional	`function`Callback for onMouseEnter event	YesNo
onMouseLeaveOptional	`function`Callback for onMouseLeave event	YesNo
onFocusOptional	`function`Callback for onFocus event	YesNo
onBlurOptional	`function`Callback for onBlur event	YesNo

Users need to define a specific date range for filtering, reporting, or analysis. .

#Placement

PeriodPicker is typically used in the following places:

Form: Select time period for report progress (e.g Edit scheduled report)
Filter: Filter data in charts to track progress of issues (e.g Accessibility overview)

#Style

Siteimprove Design System: Adhere to Siteimprove's guidelines for color, typography, and spacing. If you are not using a component from Fancy, match the styling of your PeriodPicker to existing components for visual consistency.
Always offer a logical default range (e.g., "Last 7 Days") to streamline common tasks.
Visually indicate the active range at all times.
Visually connect the selected dates within the calendar view to the button's display.
Prevent users from selecting invalid ranges (e.g., end date before start date). Provide clear error messages if needed.

#Do not use when

Users only need to select a single date (use a Date picker instead).

#Accessibility

For designers

Clear labels and instructions.

For developers

This component comes with built-in accessibility, no extra work required.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

Use concise labels for presets (e.g., "Last Month").

Period picker

This is a Lab component!

#Examples

#Usage with hidden presets

#Usage with condensed variant

#Usage with time zone conversion

#Usage with UTC offset

#Usage with includeToday option

#Usage with week start

#Properties

#Guidelines

#Best practices

#General

#Placement

#Style

#Do not use when

#Accessibility

For designers

For developers

#Writing